JBoss.orgCommunity Documentation

JBoss Communications SS7 Stack User Guide


Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Provide feedback to the authors!
1. Introduction to JBoss Communications SS7 Stack
1.1. Time Division Multiplexing
2. The Basics
2.1. Linkset
2.2. Shell Management client
2.3. SS7 Service
2.4. JBoss Communications SS7 Stack Usage
3. Installation and Running
3.1. Installing
3.1.1. Binary Service
3.1.2. Installing Binary
3.1.3. Running JBoss Communications SS7 Stack
3.2. Configuring JBoss Communications SS7 Stack
3.2.1. Configuring LinksetFactory
3.2.2. Configuring LinksetManager
3.2.3. Configuring ShellExecutor
3.2.4. Configuring SS7Service
3.3. Setup from source
3.3.1. Release Source Code Building
3.3.2. Development Trunk Source Building
4. Hardware Setup
4.1. Sangoma
4.2. Diguim
4.3. Dialogic
5. Shell Command Line
5.1. Introduction
5.2. Starting
5.3. Linkset Management
5.3.1. Create Linkset
5.3.2. Remove Linkset
5.3.3. Activate Linkset
5.3.4. Deactivate Linkset
5.3.5. Create Link
5.3.6. Remove Link
5.3.7. Activate Link
5.3.8. Deactivate Link
5.3.9. Show status
5.4. SCCP Management
6. SCCP
6.1. Routing Management
6.2. Routing Configuration
6.3. JBoss Communications SS7 Stack SCCP Usage
6.4. Access Point
6.5. SCCP User Part Example
7. TCAP
7.1. JBoss Communications SS7 Stack TCAP Usage
7.2. JBoss Communications SS7 Stack TCAP User Part Example
8. MAP
8.1. SS7 Stack MAP Usage
8.2. SS7 Stack MAP Usage
A. Java Development Kit (JDK): Installing, Configuring and Running
B. Setting the JBOSS_HOME Environment Variable
C. Revision History
Index

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:

The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:

The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in the the Issue Tracker, against the product JBoss Communications SS7 Stack , or contact the authors.

When submitting a bug report, be sure to mention the manual's identifier: SS7Stack_User_Guide

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

Important

Spaces where introduced in in some tables and code listings to ensure proper page render.

Common Channel Signaling System No. 7 (i.e., SS7 or C7) is a global standard for telecommunications defined by the International Telecommunication Union (ITU) Telecommunication Standardization Sector (ITU-T) . The standard defines the procedures and protocol by which network elements in the public switched telephone network (PSTN) ) exchange information over a digital signaling network to effect wireless (cellular) and wireline call setup, routing and control. The ITU definition of SS7 allows for national variants such as the American National Standards Institute (ANSI) and Bell Communications Research (Telcordia Technologies) standards used in North America and the European Telecommunications Standards Institute ( ETSI ) standard used in Europe.

The hardware and software functions of the SS7 protocol are divided into functional abstractions called "levels". These levels map loosely to the Open Systems Interconnect (OSI) 7-layer model defined by the International Standards Organization (ISO) .

SS7 Stack overview

JBoss Communications SS7 Stack is software based SS7 protocol implementation providing Level 2 and above.

The JBoss Communications SS7 Stack is logically divided into two sections. The lower section includes SS7 Level 3 and below. The lower section is influenced by type of SS7 hardware (Level 1) used. The upper section includes SS7 Level 4 and above. This logical division is widely based on flexibility of JBoss Communications SS7 Stack to allow usage of any SS7 hardware available in the market and yet JBoss Communications SS7 Stack Level 4 and above remains the same.

Important

Be aware, JBoss Communications SS7 Stack is subject to changes as it is under active development!

JBoss Communications SS7 Stack consists of following functional blocks:

Mobicents SS7 stack at its core requires only Java 1.5(Java SE) if you are using only M3UALinkset. However if you plan to use DahdiLinkset or DialogicLinkset, respective SS7 cards needs to be installed on the server along with native libraries.

A simple way to get started is to download and install binary. This will provide you with all the dependencies you need to get going. You can obtain binary release from NOT AVAILABLE

The JBoss Communications SS7 Stack binary is broken down into a few modules.

The following is a description of the important services and libraries that make up JBoss Communications SS7 Stack

Binary release has following layout:

The JBoss Communications SS7 Stack binary requires that you have JBoss Application Server installed and JBOSS_HOME system property set. To know further details on setting JBOSS_HOME look Appendix B, Setting the JBOSS_HOME Environment Variable

Once JBOSS_HOME is properly set, use ant to deploy the mobicents-ss7-service, shell scripts and shell library.

Important

Ant 1.6 (or higher) is used to install the binary. Instructions for using Ant, including install, can be found at http://ant.apache.org/

[usr]$ cd ss7-1.0.0.BETA6/ss7
[usr]$ ant deploy
			

To undeploy these services

[usr]$ cd ss7-1.0.0.BETA6/ss7
[usr]$ ant undeploy
			

While above steps will deploy the necessary ss7 service and shell components, the java.library.path should be set to point the directory containing native component or should be copied to JBoss native library path manually. This step is only required if you are using the SS7 board on server.

Starting or stopping JBoss Communications SS7 Stack is no different than starting or stopping JBoss Application Server

Once installed, you can run server by executing the run.sh (Unix) or run.bat (Microsoft Windows) startup scripts in the <install_directory>/bin directory (on Unix or Windows). If the service started properly you should see following lines in the Unix terminal or Command Prompt depending on your environment:

23:22:26,079 INFO  [LinksetManager] SS7 configuration file path /home/abhayani/workarea/mobicents/jboss-5.1.0.GA/server/default/data/linksetmanager.xml
23:22:26,141 INFO  [LinksetManager] Started LinksetManager
23:22:26,199 INFO  [SS7Service] Starting SCCP stack...
23:22:26,229 INFO  [SccpStackImpl] Starting ...
23:22:26,230 INFO  [RouterImpl] SCCP Router configuration file: /home/abhayani/workarea/mobicents/jboss-5.1.0.GA/server/default/deploy/mobicents-ss7-service/sccp-routing.txt
23:22:26,261 INFO  [SS7Service] SCCP stack Started. SccpProvider bound to java:/mobicents/ss7/sccp
23:22:26,261 INFO  [ShellExecutor] Starting SS7 management shell environment
23:22:26,270 INFO  [ShellExecutor] ShellExecutor listening at /127.0.0.1:3435
23:22:26,270 INFO  [SS7Service] [[[[[[[[[ Mobicents SS7 service started ]]]]]]]]]

				

If you have started ss7-1.0.0.BETA6 for the first time, there are no Linkset defined. You need to use Shell Client to connect to ss7-1.0.0.BETA6 as defined in ??? and create Linkset as per your need and SS7 card installed

Once the Linkset are defined, the state and configuration of Linkset and Link is persisted by LinksetManager which stands server re-start.

Configuration is done through an XML descriptor named jboss-beans.xml and is located at $JBOSS_HOME/server/profile_name/deploy/mobicents-ss7-service/META-INF, where profile_name is the server profile name.

SS7Service acts as core engine binding all the components together. To get holistic view of SS7 Service look at Section 2.3, “SS7 Service”


    <bean name="SS7Service" class="org.mobicents.ss7.SS7Service">
        <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="org.mobicents.ss7:service=SS7Service",exposedInterface=org.mobicents.ss7.SS7ServiceMBean.class,registerDirectly=true)</annotation>
        <property name="jndiName">java:/mobicents/ss7/sccp</property>
        <property name="configPath">${catalina.home}/deploy/mobicents-ss7-service/sccp-routing.txt</property>
        <property name="linksetManager"><inject bean="LinksetManager" /></property>
        <property name="shellExecutor"><inject bean="ShellExecutor" /></property>       
    </bean>

SS7 service creates new instance of SCCP stack and binds it to JNDI address java:/mobicents/ss7/sccp. The JNDI name can be configured to any valid JNDI name specific to your application.

configPath is configuration path for SCCP Stack. To know more about SCCP configuration refer Chapter 6, SCCP

linksetManager property holds the reference to LinksetManager bean

shellExecutor property holds the reference to ShellExecutor bean. SS7Service creates link between ShellExecutor and LinksetManager such that all commands for linkset are directed to LinksetManager.

JBoss Communications SS7 Stack is an open source project, instructions for building from source are part of the manual! Building from source means you can stay on top with the latest features. Whilst aspects of JBoss Communications SS7 Stack are quite complicated, you may find ways to become contributors.

JBoss Communications SS7 Stack works with JDK1.5 and above. you will need also need to have the following tools installed. Minimum requirement version numbers provided.

  1. Downloading the source code

    Use SVN to checkout a specific release source, the base URL is ?, then add the specific release version, lets consider 1.0.0.BETA6.

    [usr]$ svn co ?/ss7-1.0.0.BETA6
  2. Building the source code

    Now that we have the source the next step is to build and install the source. JBoss Communications SS7 Stack uses Maven 2 to build the system. There are two profiles available "dahdilinux" and "dialogiclinux" appart from default profile that doesn't try to compile the native modules.

    Use "dahdilinux" profile if linux server on which this code is built already has dahdi module installed. Make sure you pass "include.zap" system property pointing to correct directory where dahdi is installed

    [usr]$ cd ss7-1.0.0.BETA6
    [usr]$ mvn install -Pdahdilinux -Dinclude.zap=/usr/include/dahdi
    				    

    Use "dialogiclinux" profile if linux server on which this code is built already has dialogic module installed. Make sure you pass "include.dialogic" system property pointing to correct directory where dialogic libraries are installed

    [usr]$ cd ss7-1.0.0.BETA6
    [usr]$ mvn install -Pdialogclinux -Dinclude.dialogic=/usr/include/dialogic
    				    

    To build JBoss Communications SS7 Stack without building any native libraries use

    [usr]$ cd ss7-1.0.0.BETA6
    [usr]$ mvn install 
    				    

    Use Ant to build the binary .

    [usr]$ cd ss7-1.0.0.BETA6/release
    [usr]$ ant
    				    

This chapter contains reference to configure hardware drivers for different types of SS7 cards.

JBoss Communications SS7 Stack supports dahdi based SS7 cards like diguim and sangoma. Generally dahdi based SS7 crads doesn't have MTP2/MTP3 support on board and relies on external software to provide these services.

JBoss Communications SS7 Stack also supports dialogic based SS7 cards which has on board support for MTP2/MTP3

Linksets are managed by linkset command. It allows to perform following:

The Signaling Connection Control Part (SCCP) is defined in ITU-T Recommendations Q.711-Q.716. SCCP sits on top of Message Transfer Part 3 (MTP3) in the SS7 protocol stack. The SCCP provides additional network layer functions to provide transfer of noncircuit-related (NCR) signaling information, application management procedures and alternative and more flexible methods of routing.

Routing rules are persisted within file. By default its sccp-routing.txt. This file is managed by SCCP stack and SS7 Service , it is not encouraged practice to edit this file by hand. However for complete rerefence, you can find structure of this file below:



sequence;pattern;translation;mtpinfo

                

Example file entry looks as follows:


sequence

is set to 0, since its only rule in a file(or first).

pattern

matches natioan mobile number with following digits: 9023629581

translation

changes destination to international mobile with following digits: 79023629581. Since no sub-system number is present, this rule requires mtpinfo to indicate target.

mtpinfo

indicates link through which message will be sent to next hop. Link:

  • Belongs to linkset with name equal to linkset.

  • Adjacent point code is equal to 14083.

  • Origin point code is equal to 14155.

  • Signaling link selector is equal to 0. Note that this value may be overriden by transport layer.

The org.mobicents.protocols.ss7.sccp.SccpStack is responsible for taking the config file and turning it into org.mobicents.protocols.ss7.sccp.Router. All the sccp messages sent bu SCCP User Part are routed as per the rule configured in Router

The SCCP User Part gets handle to SccpStack by doing JNDI look-up as explained in Section 6.4, “Access Point”

SccpStack exposes org.mobicents.protocols.ss7.sccp.SccpProvider that interacts directly with SccpStack. This interface defines the methods that will be used by SCCP User Part to send org.mobicents.protocols.ss7.sccp.message.SccpMessage and register org.mobicents.protocols.ss7.sccp.SccpListener's to listen for incoming SCCP messages.

SCCP User Part registers SccpListener for specific local org.mobicents.protocols.ss7.sccp.parameter.SccpAddress. For every incoming SccpMessage, if the called party address matches with this local SccpAddress, the corresponding SccpListner is called.

SccpProvider also exposes org.mobicents.protocols.ss7.sccp.message.MessageFactory and org.mobicents.protocols.ss7.sccp.parameter.ParameterFactory to create new concrete SccpMessage viz., org.mobicents.protocols.ss7.sccp.message.UnitData or org.mobicents.protocols.ss7.sccp.message.XUnitData passing the corresponding parameters created by leveraging ParameterFactory.

The UML class diagram looks like

SS7 Service provides user with access point to SCCP protocol/stack.

To get handle to SccpStack do the JNDI look-up passing the JNDI name configured in SS7 service as explained in Section 3.2.4, “Configuring SS7Service”

    

        private static SccpProvider getSccpProvider() throws NamingException {
    
            // no arg is ok, if we run in JBoss
            InitialContext ctx = new InitialContext();
            try {
                String providerJndiName = "/mobicents/ss7/sccp";
                return ((SccpStack) ctx.lookup(providerJndiName)).getSccpProvider();
    
            } finally {
                ctx.close();
            }
        }
            
        

Below is SCCP User Part example listening for incoming SCCP message and sending back new message



public class Test implements SccpListener {
    private SccpProvider sccpProvider;
    private SccpAddress localAddress;
    private static SccpProvider getSccpProvider() throws NamingException {
        // no arg is ok, if we run in JBoss
        InitialContext ctx = new InitialContext();
        try {
            String providerJndiName = "/mobicents/ss7/sccp";
            return ((SccpStack) ctx.lookup(providerJndiName)).getSccpProvider();
        } finally {
            ctx.close();
        }
    }
    public void start() throws Excetpion {
        this.sccpProvider = getSccpProvider();
        int translationType = 0;
        int subSystemNumber = 0;
        GlobalTitle gt = GlobalTitle.getInstance(translationType,
                NumberingPlan.ISDN_MOBILE, NatureOfAddress.NATIONAL, "1234");
        localAddress = new SccpAddress(gt, 0);
        this.sccpProvider.registerSccpListener(localAddress, this);
    }
    public void stop() {
        this.sccpProvider.deregisterSccpListener(localAddress);
    }
    public void onMessage(SccpMessage message) {
        if (message.getType() == MessageType.UDT) {
            throw new IlleagalArgumentException("Dont like UDT");
        } else if (message.getType() == MessageType.XUDT) {
            XUnitData xudt = (XUnitData) message;
            localAddress = ((XUnitData) message).getCalledPartyAddress();
            SccpAddress remoteAddress = ((XUnitData) message)
                    .getCallingPartyAddress();
            // now decode content
            byte[] data = xudt.getData();
            // some data encoded in
            CallRequest cr = new CallRequest(data);
            byte[] answerData;
            if (cr.getCallee().equals(this.localAddress)) {
                EstablihsCallAnswer eca = new EstablihsCallAnswer(cr);
                answerData = eca.encode();
            } else {
                TearDownCallAnswer tdca = new TearDownCallAnswer(cr);
                answerData = tdca.encode();
            }
            HopCounter hc = this.sccpProvider.getParameterFactory()
                    .createHopCounter(5);
            XUnitData sccpAnswer = this.sccpProvider
                    .getMessageFactory()
                    .createXUnitData(hc, xudt.getProtocolClass(),
                            message.getCallingPartyAddress(), this.localAddress);
            this.sccpProvider.send(sccpAnswer);
        }
    }
}
        

The Transaction Capabilities Application Part (TCAP) is defined in ITU-T Recommendations Q.771-Q.775. TCAP allows services at network nodes to communicate with each other using an agreed-upon set of data elements. Its primary purpose is to facilitate multiple concurrent dialogs between the same sub-systems on the same machines, using Transaction IDs to differentiate these, similar to the way TCP ports facilitate multiplexing connections between the same IP addresses on the Internet.

org.mobicents.protocols.ss7.tcap.api.TCAPStack interface defines the methods required to represent TCAP Protocol Stack. TCAPStack exposes org.mobicents.protocols.ss7.tcap.api.TCAPProvider that interacts directly with TCAPStack. TCAPProvider defines methods that will be used by TCAP User Part to create new org.mobicents.protocols.ss7.tcap.api.tc.dialog.Dialog to be sent across network. TCAP User Part also registers org.mobicents.protocols.ss7.tcap.api.TCListener to listen TCAP messages.

TCAPProvider also exposes org.mobicents.protocols.ss7.tcap.api.DialogPrimitiveFactory to create dialog primitives and org.mobicents.protocols.ss7.tcap.api.ComponentPrimitiveFactory to create components. Components are a means of invoking an operation at a remote node

The UML Class Diagram looks like

org.mobicents.protocols.ss7.tcap.TCAPStackImpl is concrete implementation of TCAPStack. The TCAP User Part creates instance of TCAPStackImpl passing the reference of SccpProvider and new instance of SccpAddress representing address to which bind listenr. TCAP stack creates internaly JBoss Communications MAP Stack implementation. Passed SccpAddress is used to match against incoming messages destination address.

    

            SccpProvider sccpProvider = getSccpProvider(); //JNDI lookup of SCCP Stack and get Provider
            SccpAddress localAddress createLocalAddress();      
    
            TCAPStack tcapStack = new TCAPStackImpl(sccpPprovider, localAddress);
    
              
            ...
            
            private SccpAddress createLocalAddress()
            {
                int translationType = 0;
        
                int subSystemNumber = 0;
        
        
                GlobalTitle gt = GlobalTitle.getInstance(translationType,
        
                NumberingPlan.ISDN_MOBILE, NatureOfAddress.NATIONAL, "1234");
    
                SccpAddress localAddress = new SccpAddress(gt, 0);
                return localAddress;
            }
    
            
        

The reference to SccpProvider is received from SccpStack. To get handle to SccpStack do the JNDI look-up passing the JNDI name configured in SS7 service as explained in Section 6.4, “Access Point”

The TCAP User Part should register the concrete implementation of TCListener with TCAPProvider to listen for incoming TCAP messages.



    public class Client implements TCListener{
            .....       
            tcapProvider = tcapStack.getProvider();
            tcapProvider.addTCListener(this);
            ....
    }               
            
        

The TCAP User Part leverages TCAPProvider to create new Dialog. The component's between the nodes are exchanged within this Dialog



        clientDialog = this.tcapProvider.getNewDialog(thisAddress, remoteAddress);          
        
    

The TCAP User Part leverages ComponentPrimitiveFactory to create new components. These components are sent usig the dialog



        //create some INVOKE
        Invoke invoke = cpFactory.createTCInvokeRequest();
        invoke.setInvokeId(this.clientDialog.getNewInvokeId());
        invoke.setOperationCode(cpFactory.createOperationCode(true,new Long(12)));
        //no parameter
        this.clientDialog.sendComponent(invoke);        
        
    

Below is TCAP User Part example. This example creates dialog and exchanges messages withing structured dialog. Refer to source for function calls:

    

        
public class Client implements TCListener{
    //encoded Application Context Name
    public static final long[] _ACN_ = new long[] { 0, 4, 0, 0, 1, 0, 19, 2 };
    
    private TCAPStack stack;
    private SccpAddress thisAddress;
    private SccpAddress remoteAddress;
    
    private TCAPProvider tcapProvider;
    private Dialog clientDialog;
    
    Client(SccpProvider sccpPprovider, SccpAddress thisAddress,SccpAddress remoteAddress) {
        super();
        this.stack = new TCAPStackImpl(sccpPprovider,thisAddress); //pass address, so stack can register in SCCP
        this.runningTestCase = runningTestCase;
        this.thisAddress = thisAddress;
        this.remoteAddress = remoteAddress;
        this.tcapProvider = this.stack.getProvider();
        this.tcapProvider.addTCListener(this);
    }
    private static SccpProvider getSccpProvider() throws NamingException {
        // no arg is ok, if we run in JBoss
        InitialContext ctx = new InitialContext();
        try {
            String providerJndiName = "/mobicents/ss7/sccp";
            return ((SccpStack) ctx.lookup(providerJndiName)).getSccpProvider();
        } finally {
            ctx.close();
        }
    }
    public void start() throws TCAPException, TCAPSendException {
        clientDialog = this.tcapProvider.getNewDialog(thisAddress, remoteAddress);
        ComponentPrimitiveFactory cpFactory = this.tcapProvider.getComponentPrimitiveFactory();
        
        //create some INVOKE
        Invoke invoke = cpFactory.createTCInvokeRequest();
        invoke.setInvokeId(this.clientDialog.getNewInvokeId());
        
        invoke.setOperationCode(cpFactory.createOperationCode(true,new Long(12)));
        //no parameter
        this.clientDialog.sendComponent(invoke);
        
        ApplicationContextName acn = this.tcapProvider.getDialogPrimitiveFactory()
            .createApplicationContextName(_ACN_);
        //UI is optional!
        TCBeginRequest tcbr = this.tcapProvider.getDialogPrimitiveFactory().createBegin(this.clientDialog);
        tcbr.setApplicationContextName(acn);
        this.clientDialog.send(tcbr);
    }
    
    public void dialogReleased(Dialog d) {
    
        
    }
    public void onInvokeTimeout(Invoke tcInvokeRequest) {
    
    }
    public void onTCBegin(TCBeginIndication ind) {
        
        
    }
    public void onTCContinue(TCContinueIndication ind) {
        //send end
        TCEndRequest end = this.tcapProvider.getDialogPrimitiveFactory().createEnd(ind.getDialog());
        end.setTermination(TerminationType.Basic);
        try {
            ind.getDialog().send(end);
            
        } catch (TCAPSendException e) {
            throw new RuntimeException(e);
        }
    }
    public void onTCEnd(TCEndIndication ind) {
        //should not happen, in this scenario, we send data.
    }
    public void onTCUni(TCUniIndication ind) {
        //not going to happen
    
    }
    public void onTCPAbort(TCPAbortIndication ind) {
        // TODO Auto-generated method stub
        
    }
    public void onTCUserAbort(TCUserAbortIndication ind) {
        // TODO Auto-generated method stub
        
    }
    
    
    public static void main(String[] args)
    {
    
        int translationType = 0;
        int subSystemNumber = 0; 
        GlobalTitle gt = GlobalTitle.getInstance(translationType,NumberingPlan.ISDN_MOBILE,NatureOfAddress.NATIONAL, "1234");
        SccpAddress localAddress = new SccpAddress(gt,0);
        
        gt = GlobalTitle.getInstance(translationType,NumberingPlan.ISDN_MOBILE,NatureOfAddress.NATIONAL, "1572582");
        SccpAddress remoteAddress = new SccpAddress(gt,0);
        Client c = new Client(getSccpProvider(),localAddress,remoteAddress);
    }
    
}
        
        

Mobile application part ( MAP ) is the protocol that is used to allow the GSM network nodes within the Network Switching Subsystem ( NSS ) to communicate with each other to provide services, such as roaming capability, text messaging ( SMS ), Unstructured Supplementary Service Data ( USSD ) and subscriber authentication. MAP provides an application layer on which to build the services that support a GSM network. This application layer provides a standardized set of services. MAP uses the services of the SS7 network, specifically the Signaling Connection Control Part ( SCCP ) and the Transaction Capabilities Application Part ( TCAP )

Important

For better understanding of this chapter please read GSM 09.02.

org.mobicents.protocols.ss7.map.api.MAPStack interface defines the methods required to represent MAP Protocol Stack. MAPStack exposes org.mobicents.protocols.ss7.map.api.MAPProvider that interacts directly with MAPStack. This interface defines the methods that will be used by any registered MAP User application implementing the org.mobicents.protocols.ss7.map.api.MAPDialogListener and org.mobicents.protocols.ss7.map.api.MAPServiceListener interface to listen MAP messages and dialogue handling primitives. The class diagram looks like

org.mobicents.protocols.ss7.map.MAPStackImpl is concrete implementation of MAPStack . The MAP User application creates instance of MAPStackImpl passing the reference of SccpProvider and new instance of SccpAddress representing address to which bind listener. This addess will be used to match against destination address in SCCP messages.

    

        SccpProvider sccpProvider = getSccpProvider(); //JNDI lookup of SCCP Stack and get Provider
        SccpAddress localAddress createLocalAddress();      
        MAPStackImpl mapStack = new MAPStackImpl(sccpPprovider, localAddress);
        
        ...
        
        private SccpAddress createLocalAddress()
        {
            int translationType = 0;
    
            int subSystemNumber = 0;
    
    
            GlobalTitle gt = GlobalTitle.getInstance(translationType,
    
            NumberingPlan.ISDN_MOBILE, NatureOfAddress.NATIONAL, "1234");
            SccpAddress localAddress = new SccpAddress(gt, 0);
            return localAddress;
        }
        
        
    

The reference to SccpProvider is received from SccpStack . To get handle to SccpStack do the JNDI look-up passing the JNDI name configured in SS7 service as explained in Section 6.4, “Access Point”

The MAP User application should register the concrete implementation of MAPDialogListener and MAPServiceListener with MAPProvider to listen for incoming MAP Dialog and MAP Primitive messages.



public class MAPExample implements MAPDialogListener, MAPServiceListener {
        .....       
        mapProvider = mapStack.getMAPProvider();
        mapProvider.addMAPDialogListener(this);
        mapProvider.addMAPServiceListener(this);
        ....
}               
        
    

The MAP User Application leverages MapServiceFactory to create instance of USSDString and AddressString



        MapServiceFactory servFact = mapProvider.getMapServiceFactory();
        USSDString ussdString = servFact.createUSSDString("*125*+31628839999#",
                null);
        AddressString msisdn = this.servFact.createAddressString(
                AddressNature.international_number, NumberingPlan.ISDN,
                "31628838002");             
        
    

The MAP User Application leverages MAPProvider to create new MAPDialog and send USSD message



        // First create Dialog
        MAPDialog mapDialog = mapProvider.createNewDialog(
                MAPApplicationContext.networkUnstructuredSsContextV2,
                destAddress, destReference, origAddress, origReference);
        byte ussdDataCodingScheme = 0x0f;
        // USSD String: *125*+31628839999#
        // The Charset is null, here we let system use default Charset (UTF-7 as
        // explained in GSM 03.38. However if MAP User wants, it can set its own
        // impl of Charset
        USSDString ussdString = servFact.createUSSDString("*125*+31628839999#",
                null);
        AddressString msisdn = this.servFact.createAddressString(
                AddressNature.international_number, NumberingPlan.ISDN,
                "31628838002");
        mapDialog.addProcessUnstructuredSSRequest(ussdDataCodingScheme,
                ussdString, msisdn);
        // This will initiate the TC-BEGIN with INVOKE component
        mapDialog.send();           
        
    

The complete example looks like



public class MAPExample implements MAPDialogListener, MAPServiceListener {
    private MAPStack mapStack;
    private MAPProvider mapProvider;
    MapServiceFactory servFact;
    SccpAddress destAddress = null;
    // The address created by passing the AddressNature, NumberingPlan and
    // actual address
    AddressString destReference = servFact.createAddressString(
            AddressNature.international_number, NumberingPlan.land_mobile,
            "204208300008002");
    SccpAddress origAddress = null;
    AddressString origReference = servFact.createAddressString(
            AddressNature.international_number, NumberingPlan.ISDN,
            "31628968300");
    MAPExample(SccpProvider sccpPprovider, SccpAddress address,
            SccpAddress remoteAddress) {
        origAddress = address;
        destAddress = remoteAddress;
        mapStack = new MAPStackImpl(sccpPprovider, origAddress);
        mapProvider = mapStack.getMAPProvider();
        servFact = mapProvider.getMapServiceFactory();
        mapProvider.addMAPDialogListener(this);
        mapProvider.addMAPServiceListener(this);
    }
    private static SccpProvider getSccpProvider() throws NamingException {
        // no arg is ok, if we run in JBoss
        InitialContext ctx = new InitialContext();
        try {
            String providerJndiName = "/mobicents/ss7/sccp";
            return ((SccpStack) ctx.lookup(providerJndiName)).getSccpProvider();
        } finally {
            ctx.close();
        }
    }
    private static SccpAddress createLocalAddress() {
        GlobalTitle gt = GlobalTitle
                .getInstance(
                        NatureOfAddress.NATIONAL.getValue(),
                        org.mobicents.protocols.ss7.indicator.NumberingPlan.ISDN_MOBILE,
                        NatureOfAddress.NATIONAL, "1234");
        return new SccpAddress(gt, 0); // 0 is Sub-System number
    }
    private static SccpAddress createRemoteAddress() {
        GlobalTitle gt = GlobalTitle
                .getInstance(
                        NatureOfAddress.NATIONAL.getValue(),
                        org.mobicents.protocols.ss7.indicator.NumberingPlan.ISDN_MOBILE,
                        NatureOfAddress.NATIONAL, "1572582");
        return new SccpAddress(gt, 0); // 0 is Sub-System number
    }
    public void run() throws Exception {
        // First create Dialog
        MAPDialog mapDialog = mapProvider.createNewDialog(
                MAPApplicationContext.networkUnstructuredSsContextV2,
                destAddress, destReference, origAddress, origReference);
        // The dataCodingScheme is still byte, as I am not exactly getting how
        // to encode/decode this.
        byte ussdDataCodingScheme = 0x0f;
        // USSD String: *125*+31628839999#
        // The Charset is null, here we let system use default Charset (UTF-7 as
        // explained in GSM 03.38. However if MAP User wants, it can set its own
        // impl of Charset
        USSDString ussdString = servFact.createUSSDString("*125*+31628839999#",
                null);
        AddressString msisdn = this.servFact.createAddressString(
                AddressNature.international_number, NumberingPlan.ISDN,
                "31628838002");
        mapDialog.addProcessUnstructuredSSRequest(ussdDataCodingScheme,
                ussdString, msisdn);
        // This will initiate the TC-BEGIN with INVOKE component
        mapDialog.send();
    }
    public void onMAPAcceptInfo(MAPAcceptInfo mapAccptInfo) {
        // TODO Auto-generated method stub
    }
    public void onMAPCloseInfo(MAPCloseInfo mapCloseInfo) {
        // TODO Auto-generated method stub
    }
    public void onMAPOpenInfo(MAPOpenInfo mapOpenInfo) {
        // TODO Auto-generated method stub
    }
    public void onMAPProviderAbortInfo(MAPProviderAbortInfo mapProviderAbortInfo) {
        // TODO Auto-generated method stub
    }
    public void onMAPRefuseInfo(MAPRefuseInfo mapRefuseInfo) {
        // TODO Auto-generated method stub
    }
    public void onMAPUserAbortInfo(MAPUserAbortInfo mapUserAbortInfo) {
        // TODO Auto-generated method stub
    }
    public void onProcessUnstructuredSSIndication(
            ProcessUnstructuredSSIndication procUnstrInd) {
        // TODO Auto-generated method stub
    }
    public void onUnstructuredSSIndication(UnstructuredSSIndication unstrInd) {
        // TODO Auto-generated method stub
    }
    public static void main(String[] args) throws Exception {
        SccpProvider sccpProvider = getSccpProvider(); // JNDI lookup of SCCP
        SccpAddress localAddress = createLocalAddress();
        SccpAddress remoteAddress = createRemoteAddress();
        MAPExample example = new MAPExample(sccpProvider, localAddress,
                remoteAddress);
        example.run();
    }
}           
        
    

The JBoss Communications Platform is written in Java; therefore, before running any JBoss Communications server, you must have a working Java Runtime Environment (JRE) or Java Development Kit (JDK) installed on your system. In addition, the JRE or JDK you are using to run JBoss Communications must be version 5 or higher[1].

Should I Install the JRE or JDK?

Although you can run JBoss Communications servers using the Java Runtime Environment, we assume that most users are developers interested in developing Java-based, JBoss Communications-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.

Should I Install the 32-Bit or the 64-Bit JDK, and Does It Matter?

Briefly stated: if you are running on a 64-Bit Linux or Windows platform, you should consider installing and running the 64-bit JDK over the 32-bit one. Here are some heuristics for determining whether you would rather run the 64-bit Java Virtual Machine (JVM) over its 32-bit cousin for your application:

  • Wider datapath: the pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications when using a 64-bit JVM.

  • 64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.

  • Applications that run with more than 1.5 GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.

  • Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.

Note that the following instructions detail how to download and install the 32-bit JDK, although the steps are nearly identical for installing the 64-bit version.

Downloading

You can download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp. Click on the Download link next to "JDK 5.0 Update <x>" (where <x> is the latest minor version release number). On the next page, select your language and platform (both architecture—whether 32- or 64-bit—and operating system), read and agree to the Java Development Kit 5.0 License Agreement, and proceed to the download page.

The Sun website will present two download alternatives to you: one is an RPM inside a self-extracting file (for example, jdk-1_5_0_16-linux-i586-rpm.bin), and the other is merely a self-extracting file (e.g. jdk-1_5_0_16-linux-i586.bin). If you are installing the JDK on Red Hat Enterprise Linux, Fedora, or another RPM-based Linux system, we suggest that you download the self-extracting file containing the RPM package, which will set up and use the SysV service scripts in addition to installing the JDK. We also suggest installing the self-extracting RPM file if you will be running JBoss Communications in a production environment.

Installing

The following procedures detail how to install the Java Development Kit on both Linux and Windows.

Important

You do not need to install a -compat package in addition to the JDK if you installed the self-extracting RPM file! The -compat package merely performs the same SysV service script set up that the RPM version of the JDK installer does.

Configuring

Configuring your system for the JDK consists in two tasks: setting the JAVA_HOME environment variable, and ensuring that the system is using the proper JDK (or JRE) using the alternatives command. Setting JAVA_HOME usually overrides the values for java, javac and java_sdk_1.5.0 in alternatives, but we will set them all just to be safe and consistent.

Setting the JAVA_HOME Environment Variable on Generic Linux

After installing the JDK, you must ensure that the JAVA_HOME environment variable exists and points to the location of your JDK installation.

Setting the JAVA_HOME Environment Variable on Linux

You can determine whether JAVA_HOME is set on your system by echoing it on the command line:

~]$ echo $JAVA_HOME

If JAVA_HOME is not set already, then you must set its value to the location of the JDK installation on your system. You can do this by adding two lines to your personal ~/.bashrc configuration file. Open ~/.bashrc (or create it if it doesn't exist) and add a line similar to the following one anywhere inside the file:

export JAVA_HOME="/usr/lib/jvm/jdk1.5.0_<version>"

You should also set this environment variable for any other users who will be running JBoss Communications (any environment variables exported from ~/.bashrc files are local to that user).

Setting java, javac and java_sdk_1.5.0 Using the alternatives command
Selecting the Correct System JVM on Linux using alternatives

On systems with the alternatives command, including Red Hat Enterprise Linux and Fedora, you can easily choose which JDK (or JRE) installation you wish to use, as well as which java and javac executables should be run when called.

As the root user, call /usr/sbin/alternatives with the --config java option to select between JDKs and JREs installed on your system:

root@localhost ~]$ /usr/sbin/alternatives --config java

There are 3 programs which provide 'java'.

  Selection    Command
-----------------------------------------------
   1           /usr/lib/jvm/jre-1.5.0-gcj/bin/java
   2           /usr/lib/jvm/jre-1.6.0-sun/bin/java
*+ 3         /usr/lib/jvm/jre-1.5.0-sun/bin/java


Enter to keep the current selection[+], or type selection number:

In our case, we want to use the Sun JDK, version 5, that we downloaded and installed, to run the java executable. In the alternatives information printout above, a plus (+) next to a number indicates the one currently being used. As per alternatives' instructions, pressing Enter will simply keep the current JVM, or you can enter the number corresponding to the JVM you would prefer to use.

Repeat the procedure above for the javac command and the java_sdk_1.5.0 environment variable, as the root user:

~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
Setting the JAVA_HOME Environment Variable on Windows

For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.

Testing

Finally, to make sure that you are using the correct JDK or Java version (5 or higher), and that the java executable is in your PATH, run the java -version command in the terminal from your home directory:

~]$ java -version
java version "1.5.0_16"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03)
Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling

There is usually no reason (other than space concerns) to remove a particular JDK from your system, given that you can switch between JDKs and JREs easily using alternatives, and/or by setting JAVA_HOME.

Uninstalling the JDK on Linux

On RPM-based systems, you can uninstall the JDK using the yum remove <jdk_rpm_name> command.

Uninstalling the JDK on Windows

On Windows systems, check the JDK entry in the Start menu for an uninstall command, or use Add/Remove Programs.



[1] At this point in time, it is possible to run most JBoss Communications servers, such as the JAIN SLEE, using a Java 6 JRE or JDK. Be aware, however, that presently the XML Document Management Server does not run on Java 6. We suggest checking the JBoss Communications web site, forums or discussion pages if you need to inquire about the status of running the XML Document Management Server with Java 6.

The JBoss Communications Platform (JBoss Communications) is built on top of the JBoss Enterprise Application Platform. You do not need to set the JBOSS_HOME environment variable to run any of the JBoss Communications Platform servers unless JBOSS_HOME is already set.

The best way to know for sure whether JBOSS_HOME was set previously or not is to perform a simple check which may save you time and frustration.

Checking to See If JBOSS_HOME is Set on Unix

At the command line, echo $JBOSS_HOME to see if it is currently defined in your environment:

~]$ echo $JBOSS_HOME

The JBoss Communications Platform and most JBoss Communications servers are built on top of the JBoss Enterprise Application Platform (JBoss Enterprise Application Platform). When the JBoss Communications Platform or JBoss Communications servers are built from source, then JBOSS_HOME must be set, because the JBoss Communications files are installed into (or “over top of” if you prefer) a clean JBoss Enterprise Application Platform installation, and the build process assumes that the location pointed to by the JBOSS_HOME environment variable at the time of building is the JBoss Enterprise Application Platform installation into which you want it to install the JBoss Communications files.

This guide does not detail building the JBoss Communications Platform or any JBoss Communications servers from source. It is nevertheless useful to understand the role played by JBoss AS and JBOSS_HOME in the JBoss Communications ecosystem.

The immediately-following section considers whether you need to set JBOSS_HOME at all and, if so, when. The subsequent sections detail how to set JBOSS_HOME on Unix and Windows

You DO NOT NEED to set JBOSS_HOME if...

You MUST set JBOSS_HOME if...

Naturally, if you installed the JBoss Communications Platform or one of the JBoss Communications server binary releases which do not bundle JBoss Enterprise Application Platform, yet requires it to run, then you should install before setting JBOSS_HOME or proceeding with anything else.

Setting the JBOSS_HOME Environment Variable on Unix

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform or individual JBoss Communications server that you installed. As another hint, this topmost directory contains a bin subdirectory.

Setting JBOSS_HOME in your personal ~/.bashrc startup script carries the advantage of retaining effect over reboots. Each time you log in, the environment variable is sure to be set for you, as a user. On Unix, it is possible to set JBOSS_HOME as a system-wide environment variable, by defining it in /etc/bashrc, but this method is neither recommended nor detailed in these instructions.

Procedure B.1. To Set JBOSS_HOME on Unix...

  1. Open the ~/.bashrc startup script, which is a hidden file in your home directory, in a text editor, and insert the following line on its own line while substituting for the actual install location on your system:

    export JBOSS_HOME="/home/<username>/<path>/<to>/<install_directory>"
  2. Save and close the .bashrc startup script.

  3. You should source the .bashrc script to force your change to take effect, so that JBOSS_HOME becomes set for the current session[2].

    ~]$ source ~/.bashrc
  4. Finally, ensure that JBOSS_HOME is set in the current session, and actually points to the correct location:

    Note

    The command line usage below is based upon a binary installation of the JBoss Communications Platform. In this sample output, JBOSS_HOME has been set correctly to the topmost_directory of the JBoss Communications installation. Note that if you are installing one of the standalone JBoss Communications servers (with JBoss AS bundled!), then JBOSS_HOME would point to the topmost_directory of your server installation.

    ~]$ echo $JBOSS_HOME
    /home/silas/
Setting the JBOSS_HOME Environment Variable on Windows

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform or individual JBoss Communications server that you installed. As another hint, this topmost directory contains a bin subdirectory.

For information on how to set environment variables in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.



[2] Note that any other terminals which were opened prior to your having altered .bashrc will need to source ~/.bashrc as well should they require access to JBOSS_HOME.

Revision History
Revision 1.0Wed June 2 2010Bartosz Baranowski
Creation of the JBoss Communications SS7 Stack User Guide.
Revision 1.1Tue Dec 21 2010Amit Bhayani
Creation of the JBoss Communications SS7 Stack User Guide.